Monte Library 私人知识库 资料库 EN

原始笔记

OpenAI Harness：Agent-first 工程方法

OpenAI Harness：Agent-first 工程方法（整理版）

原始资料：OpenAI《Harness engineering: leveraging Codex in an agent-first world》 原始笔记：OpenAI harness 相关笔记：[ARCHITECTURE.md 写作方法](/original-notes/self_study_notes/harness/OpenAI Harness/整理版/ARCHITECTURE（整理版）)、[rust-analyzer 架构文档示例](/original-notes/self_study_notes/harness/OpenAI Harness/整理版/architecture_example（整理版）)、[本目录索引](/original-notes/self_study_notes/harness/OpenAI Harness/整理版/索引) 整理说明：本版本结合原始笔记与可读取教程重排、补全和翻译；技术术语保留英文。

内容简要概括

Harness engineering 的重点不是让 Agent 单次生成更多代码，而是为 Agent 设计可执行、可观察、可验证的工程环境。人类负责选择目标、表达约束和判断取舍，Agent 负责实现、测试、审查与迭代；当 Agent 受阻时，应修复能力、文档、工具或反馈回路，而不是由人类直接接管代码。仓库中的结构化知识、机械约束和持续清理机制共同构成让高吞吐开发仍可维护的控制系统。

Harness engineering、Codex、Agent-first、Humans steer, Agents execute、feedback loop、observability、repository knowledge、AGENTS.md、ARCHITECTURE.md、architectural invariants、lint、structural tests、Golden Principles、technical debt

目录

1. 核心视角：把工程能力放进 Harness

Harness 指围绕 Agent 配置的工作环境、工具接口、知识结构、约束和反馈机制。它决定 Agent 能否把高层目标转化为可靠的工程结果。

核心原则是：不要只把失败当作一次模型能力不足；优先问“缺少什么能力，怎样让它既可见又可强制执行？” 可能缺少的内容包括测试命令、可复现的本地环境、领域文档、日志查询、明确验收条件或依赖边界检查。

“所有代码由 Agent 生成”是一个刻意的训练约束，而不是普适的道德规则。它迫使团队把临时人工修复转化为可复用的系统改进：

Agent 受阻
→ 找出环境、工具、文档或反馈的缺口
→ 把缺口编码为仓库能力
→ Agent 使用新能力修复并验证
→ 后续任务复用这一能力

2. 人类负责引导，Agent 负责执行

2.1 人类职责从编码转向三类杠杆

  1. 设计环境：让 Agent 可以在隔离工作区运行项目、执行测试、查看应用界面、读取日志/指标/Trace，并使用 Git 与 CI 工具。
  2. 表达意图：将任务写成目标、约束和验收标准，而非只有模糊动作。例如“服务启动低于 800 ms，并由性能测试验证”比“优化启动代码”可执行得多。
  3. 建立反馈回路：让 Agent 能观察结果、比较验收条件、修正实现并再次验证。

2.2 人类注意力是稀缺资源

在高吞吐场景中，人类无法逐行审查、手工点完每个 UI 或逐一回答 Agent 问题。系统的目标应是减少每项任务所需的人类判断；人类集中处理优先级、产品取舍、安全边界和最终责任等不可机械化的判断。

3. 让应用对 Agent 可读

Agent 无法直接访问或解释的状态，无法稳定用于决策。除代码外，还应让下面的信息进入可查询、可操作的开发环境：

  • UI：可启动的每-worktree 应用、DOM snapshot、截图、浏览器自动化与导航能力；
  • 运行信号：结构化 logs、metrics 与 traces，并为 Agent 提供查询入口；
  • 验证工具：可重复执行的测试、性能检查、lint、质量脚本和 CI；
  • 任务上下文：目标、验收条件、已知风险与关联设计文档。

理想的闭环如下：

读取任务与约束
→ 修改代码/文档/配置
→ 启动隔离环境
→ 运行测试并驱动 UI
→ 查询 logs、metrics、traces
→ 判断是否达标
→ 修正并重复，或在需要判断时升级给人类

4. 把仓库知识作为唯一可操作的事实来源

4.1 AGENTS.md 是地图，不是百科全书

巨型指令文件会挤占任务上下文、掩盖重点且很快过时。更稳健的做法是让简短的 AGENTS.md 说明入口、必读文件、验证方式和导航路径；具体的产品、设计、执行计划和质量规则放进结构化的 docs/。

AGENTS.md                 # 入口、最小规则和导航
ARCHITECTURE.md            # 高层系统地图
docs/
├── design-docs/           # 设计决策与核心信念
├── exec-plans/            # active、completed 与技术债跟踪
├── product-specs/         # 可版本化的产品规格
├── generated/             # 可再生成的派生产物
├── references/            # 外部工具/依赖的参考资料
└── QUALITY_SCORE.md       # 质量缺口与演进记录

ARCHITECTURE.md 的写作原则见 [ARCHITECTURE（整理版）](/original-notes/self_study_notes/harness/OpenAI Harness/整理版/ARCHITECTURE（整理版）)；大型项目的具体示范见 [architecture_example（整理版）](/original-notes/self_study_notes/harness/OpenAI Harness/整理版/architecture_example（整理版）)。

4.2 让知识可搜索、可版本化、可验证

重要规则若只存在于聊天记录、会议或个人记忆中，对 Agent 等同于不存在。将其放入仓库中的 Markdown、schema、可执行计划或测试中，才能版本化、审查、链接与持续校验。对于复杂、跨多小时的工作，可参考 PLANS.md execution plans 示例，将进展、决策与验证记录和代码放在同一事实来源中。

5. 用不变量和自动化约束保持架构一致性

文档只能说明期望，不能阻止漂移。应优先定义稳定的 architectural invariants，并把可机械检查的规则写入工具：

  • dependency graph 检查或结构测试：限制模块/层之间的依赖方向；
  • 类型检查和 schema 校验：在数据边界验证形状，避免“YOLO-style”猜测；
  • ESLint、AST 扫描与自定义 lint：统一命名、日志、文件大小和可靠性规则；
  • 单元/集成/端到端测试：验证行为而不是只验证说明文字；
  • CI：在合并前执行规则，并让错误信息包含可操作的修复提示。

应严格控制边界、正确性和可复现性，同时保留局部实现自由。详细的架构地图和不变量写法可参见 [ARCHITECTURE（整理版）](/original-notes/self_study_notes/harness/OpenAI Harness/整理版/ARCHITECTURE（整理版）)。

6. 从任务到合并的 Agent-first pipeline

人类：定义目标、约束、验收条件与风险边界
→ Agent：读取仓库地图与相关资料
→ Agent：在隔离 worktree 实现最小变更
→ Agent：执行测试、UI 验证与可观测性检查
→ Agent：本地自审并请求额外 Agent review
→ Agent：响应反馈、修复并重复验证
→ 人类：只在需要优先级/安全/产品判断时介入
→ 合并后：把新经验沉淀为文档、测试或 lint

计划应按复杂度分层：小改动可用简短任务计划；跨模块、耗时长或风险高的改动应建立可恢复的 execution plan，并记录进展、决策与验证证据。

7. 控制熵：持续垃圾回收与质量治理

Agent 会复用仓库中已有模式，错误模式也会扩散，因此技术债不能只靠阶段性大扫除。将团队偏好编码为 Golden Principles，再用周期性任务扫描偏差、更新质量评价、生成小型重构 PR，形成持续的“垃圾回收”。

Golden Principles 的三层实现

层次 要做什么 示例
文档层 解释原则、边界、正反例和入口 docs/engineering/golden-principles.md
机械约束层 将可验证原则自动化 lint、类型检查、依赖图、结构测试
治理层 定期发现偏差并以小变更修复 质量扫描、技术债追踪、自动创建重构 PR

例如，偏好共享 utility 以集中不变量、要求在数据边界验证输入，都可以同时写进文档与静态检查。原则一旦被编码，就能持续作用于每次 Agent 运行。

8. 落地检查清单

  • AGENTS.md 是否足够短，并能指向真实、更新频率合适的资料？
  • 是否有 [架构地图](/original-notes/self_study_notes/harness/OpenAI Harness/整理版/ARCHITECTURE（整理版）) 说明系统目标、模块边界与依赖方向？
  • Agent 是否能在隔离环境启动应用、运行测试并观察 UI？
  • logs、metrics、traces 是否可查询，且与验收指标相连？
  • 每个任务是否写清目标、不可违反的约束与可验证的完成条件？
  • 哪些规则可以从“提醒”升级为 lint、类型、测试或 CI 检查？
  • 是否定期扫描文档陈旧、重复 helper、边界违例和质量回归？
  • 人类升级点是否仅保留给产品、安全、优先级与责任判断？

Switch to English